<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>The Standard Router - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.controller.router.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.controller.router.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.controller.request.html">The Request Object</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.controller.html">Zend_Controller</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.controller.dispatcher.html">The Dispatcher</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.controller.router" class="section"><div class="info"><h1 class="title">The Standard Router</h1></div>
    

    <div class="section" id="zend.controller.router.introduction"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Controller_Router_Rewrite</span> is the standard
            framework router. Routing is the process of taking a <acronym class="acronym">URI</acronym> endpoint
            (that part of the <acronym class="acronym">URI</acronym> which comes after the base
            <acronym class="acronym">URL</acronym>) and decomposing it into parameters to determine which module,
            controller, and action of that controller should receive the
            request. This values of the module, controller, action and other
            parameters are packaged into a
            <span class="classname">Zend_Controller_Request_Http</span> object which is then
            processed by <span class="classname">Zend_Controller_Dispatcher_Standard</span>.
            Routing occurs only once: when the request is initially received and
            before the first controller is dispatched.
        </p>

        <p class="para">
            <span class="classname">Zend_Controller_Router_Rewrite</span> is designed to allow for
            mod_rewrite-like functionality using pure <acronym class="acronym">PHP</acronym> structures. It is very
            loosely based on Ruby on Rails routing and does not require any
            prior knowledge of webserver <acronym class="acronym">URL</acronym> rewriting. It is designed to work
            with a single Apache mod_rewrite rule (one of):
        </p>

        <pre class="programlisting brush: php">
RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php
</pre>


        <p class="para">
            or (preferred):
        </p>

        <pre class="programlisting brush: php">
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]
</pre>


        <p class="para">
            The rewrite router can also be used with the <acronym class="acronym">IIS</acronym> webserver (versions
            &lt;= 7.0) if <a href="http://www.isapirewrite.com" class="link external">&raquo; Isapi_Rewrite</a> has been
            installed as an Isapi extension with the following rewrite rule:
        </p>

        <pre class="programlisting brush: php">
RewriteRule ^[\w/\%]*(?:\.(?!(?:js|ico|gif|jpg|png|css|html)$)[\w\%]*$)? /index.php [I]
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>IIS Isapi_Rewrite</b><br /></span>
            

            <p class="para">
                When using <acronym class="acronym">IIS</acronym>, <var class="varname">$_SERVER[&#039;REQUEST_URI&#039;]</var> will
                either not exist, or be set as an empty string. In this case,
                <span class="classname">Zend_Controller_Request_Http</span> will attempt to use
                the <var class="varname">$_SERVER[&#039;HTTP_X_REWRITE_URL&#039;]</var> value set by the
                <span class="classname">Isapi_Rewrite</span> extension.
            </p>
        </p></blockquote>

        <p class="para">
            <acronym class="acronym">IIS</acronym> 7.0 introduces a native <acronym class="acronym">URL</acronym> rewriting module,
            and it can be configured as follows:
        </p>

        <pre class="programlisting brush: xml">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;configuration&gt;
     &lt;system.webServer&gt;
         &lt;rewrite&gt;
             &lt;rules&gt;
                 &lt;rule name=&quot;Imported Rule 1&quot; stopProcessing=&quot;true&quot;&gt;
                     &lt;match url=&quot;^.*$&quot; /&gt;
                     &lt;conditions logicalGrouping=&quot;MatchAny&quot;&gt;
                         &lt;add input=&quot;{REQUEST_FILENAME}&quot;
                             matchType=&quot;IsFile&quot; pattern=&quot;&quot;
                             ignoreCase=&quot;false&quot; /&gt;
                         &lt;add input=&quot;{REQUEST_FILENAME}&quot;
                             matchType=&quot;IsDirectory&quot;
                             pattern=&quot;&quot; ignoreCase=&quot;false&quot; /&gt;
                     &lt;/conditions&gt;
                     &lt;action type=&quot;None&quot; /&gt;
                 &lt;/rule&gt;
                 &lt;rule name=&quot;Imported Rule 2&quot; stopProcessing=&quot;true&quot;&gt;
                     &lt;match url=&quot;^.*$&quot; /&gt;
                     &lt;action type=&quot;Rewrite&quot; url=&quot;index.php&quot; /&gt;
                 &lt;/rule&gt;
             &lt;/rules&gt;
         &lt;/rewrite&gt;
     &lt;/system.webServer&gt;
&lt;/configuration&gt;
</pre>


        <p class="para">
            If using Lighttpd, the following rewrite rule is valid:
        </p>

        <pre class="programlisting brush: lighttpd">
url.rewrite-once = (
    &quot;.*\?(.*)$&quot; =&gt; &quot;/index.php?$1&quot;,
    &quot;.*\.(js|ico|gif|jpg|png|css|html)$&quot; =&gt; &quot;$0&quot;,
    &quot;&quot; =&gt; &quot;/index.php&quot;
)
</pre>

    </div>

    <div class="section" id="zend.controller.router.usage"><div class="info"><h1 class="title">Using a Router</h1></div>
        

        <p class="para">
            To properly use the rewrite router you have to instantiate it, add
            some user defined routes and inject it into the controller. The
            following code illustrates the procedure:
        </p>

        <pre class="programlisting brush: php">
// Create a router

$router = $ctrl-&gt;getRouter(); // returns a rewrite router by default
$router-&gt;addRoute(
    &#039;user&#039;,
    new Zend_Controller_Router_Route(&#039;user/:username&#039;,
                                     array(&#039;controller&#039; =&gt; &#039;user&#039;,
                                           &#039;action&#039; =&gt; &#039;info&#039;))
);
</pre>

    </div>

    <div class="section" id="zend.controller.router.basic"><div class="info"><h1 class="title">Basic Rewrite Router Operation</h1></div>
        

        <p class="para">
            The heart of the RewriteRouter is the definition of user defined
            routes. Routes are added by calling the addRoute method of
            RewriteRouter and passing in a new instance of a class implementing
            <span class="classname">Zend_Controller_Router_Route_Interface</span>. Eg.:
        </p>

        <pre class="programlisting brush: php">
$router-&gt;addRoute(&#039;user&#039;,
                  new Zend_Controller_Router_Route(&#039;user/:username&#039;));
</pre>


        <p class="para">
            Rewrite Router comes with six basic types of routes (one of which
            is special):
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <a href="zend.controller.router.html#zend.controller.router.routes.standard" class="link">Zend_Controller_Router_Route</a>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <a href="zend.controller.router.html#zend.controller.router.routes.static" class="link">Zend_Controller_Router_Route_Static</a>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <a href="zend.controller.router.html#zend.controller.router.routes.regex" class="link">Zend_Controller_Router_Route_Regex</a>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <a href="zend.controller.router.html#zend.controller.router.routes.hostname" class="link">Zend_Controller_Router_Route_Hostname</a>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <a href="zend.controller.router.html#zend.controller.router.routes.chain" class="link">Zend_Controller_Router_Route_Chain</a>
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <a href="zend.controller.router.html#zend.controller.router.default-routes" class="link">Zend_Controller_Router_Rewrite</a>
                    *
                </p>
            </li>
        </ul>

        <p class="para">
            Routes may be used numerous times to create a chain or user defined
            application routing schema. You may use any number of routes in any
            configuration, with the exception of the Module route, which should
            rather be used once and probably as the most generic route (i.e., as a
            default). Each route will be described in greater detail later on.
        </p>

        <p class="para">
            The first parameter to addRoute is the name of the route. It is used
            as a handle for getting the routes out of the router (e.g., for <acronym class="acronym">URL</acronym>
            generation purposes). The second parameter being the route itself.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                The most common use of the route name is through the means of
                <span class="classname">Zend_View</span> url helper:
            </p>

            <pre class="programlisting brush: php">
&lt;a href=
&quot;&lt;?php echo $this-&gt;url(array(&#039;username&#039; =&gt; &#039;martel&#039;), &#039;user&#039;) ?&gt;&quot;&gt;Martel&lt;/a&gt;
</pre>


            <p class="para">
                Which would result in the href: <var class="filename">user/martel</var>.
            </p>
        </p></blockquote>

        <p class="para">
            Routing is a simple process of iterating through all provided routes
            and matching its definitions to current request <acronym class="acronym">URI</acronym>. When a positive
            match is found, variable values are returned from the Route instance
            and are injected into the <span class="classname">Zend_Controller_Request</span>
            object for later use in the dispatcher as well as in user created
            controllers. On a negative match result, the next route in the chain
            is checked.
        </p>

        <p class="para">
            If you need to determine which route was matched, you can use the
             <span class="methodname">getCurrentRouteName()</span> method, which will return the
            identifier used when registering the route with the router. If you
            want the actual route object, you can use
             <span class="methodname">getCurrentRoute()</span>.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Reverse Matching</b><br /></span>
            

            <p class="para">
                Routes are matched in reverse order so make sure your most
                generic routes are defined first.
            </p>
        </p></blockquote>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Returned Values</b><br /></span>
            

            <p class="para">
                Values returned from routing come from <acronym class="acronym">URL</acronym> parameters or user
                defined route defaults. These variables are later accessible
                through the  <span class="methodname">Zend_Controller_Request::getParam()</span> or
                 <span class="methodname">Zend_Controller_Action::_getParam()</span> methods.
            </p>
        </p></blockquote>

        <p class="para">
            There are three special variables which can be used in your routes
            - &#039;module&#039;, &#039;controller&#039; and &#039;action&#039;. These special variables are
            used by <span class="classname">Zend_Controller_Dispatcher</span> to find a controller and
            action to dispatch to.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Special Variables</b><br /></span>
            

            <p class="para">
                The names of these special variables may be different if you
                choose to alter the defaults in
                <span class="classname">Zend_Controller_Request_Http</span> by means of the
                 <span class="methodname">setControllerKey()</span> and
                 <span class="methodname">setActionKey()</span> methods.
            </p>
        </p></blockquote>

    </div>

    <div class="section" id="zend.controller.router.default-routes"><div class="info"><h1 class="title">Default Routes</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Controller_Router_Rewrite</span> comes preconfigured with a default
            route, which will match <acronym class="acronym">URI</acronym>s in the shape of
            <var class="filename">controller/action</var>. Additionally, a module name may be
            specified as the first path element, allowing <acronym class="acronym">URI</acronym>s of the form
            <var class="filename">module/controller/action</var>. Finally, it will also match
            any additional parameters appended to the <acronym class="acronym">URI</acronym> by default -
            <var class="filename">controller/action/var1/value1/var2/value2</var>.
        </p>

        <p class="para">
            Some examples of how such routes are matched:
        </p>

        <pre class="programlisting brush: php">
// Assuming the following:
$ctrl-&gt;setControllerDirectory(
    array(
        &#039;default&#039; =&gt; &#039;/path/to/default/controllers&#039;,
        &#039;news&#039;    =&gt; &#039;/path/to/news/controllers&#039;,
        &#039;blog&#039;    =&gt; &#039;/path/to/blog/controllers&#039;
    )
);

Module only:
http://example/news
    module == news

Invalid module maps to controller name:
http://example/foo
    controller == foo

Module + controller:
http://example/blog/archive
    module     == blog
    controller == archive

Module + controller + action:
http://example/blog/archive/list
    module     == blog
    controller == archive
    action     == list

Module + controller + action + params:
http://example/blog/archive/list/sort/alpha/date/desc
    module     == blog
    controller == archive
    action     == list
    sort       == alpha
    date       == desc
</pre>


        <p class="para">
            The default route is simply a
            <span class="classname">Zend_Controller_Router_Route_Module</span> object stored under
            the name (index) of &#039;default&#039; in RewriteRouter. It&#039;s created
            more-or-less like below:
        </p>

        <pre class="programlisting brush: php">
$compat = new Zend_Controller_Router_Route_Module(array(),
                                                  $dispatcher,
                                                  $request);
$this-&gt;addRoute(&#039;default&#039;, $compat);
</pre>


        <p class="para">
            If you do not want this particular default route in your routing
            schema, you may override it by creating your own &#039;default&#039; route
            (i.e., storing it under the name of &#039;default&#039;) or removing it
            altogether by using  <span class="methodname">removeDefaultRoutes()</span>:
        </p>

        <pre class="programlisting brush: php">
// Remove any default routes
$router-&gt;removeDefaultRoutes();
</pre>

    </div>

    <div class="section" id="zend.controller.router.rewritebase"><div class="info"><h1 class="title">Base URL and Subdirectories</h1></div>
        

        <p class="para">
            The rewrite router can be used in subdirectories (e.g.,
            <var class="filename">http://domain.com/user/application-root/</var>) in which
            case the base <acronym class="acronym">URL</acronym> of the application
            (<var class="filename">/user/application-root</var>) should be automatically
            detected by <span class="classname">Zend_Controller_Request_Http</span> and used
            accordingly.
        </p>

        <p class="para">
            Should the base <acronym class="acronym">URL</acronym> be detected incorrectly you can override it with
            your own base path by using
            <span class="classname">Zend_Controller_Request_Http</span> and calling the
             <span class="methodname">setBaseUrl()</span> method (see <a href="zend.controller.request.html#zend.controller.request.http.baseurl" class="link">Base URL and Subdirectories</a>):
        </p>

        <pre class="programlisting brush: php">
$request-&gt;setBaseUrl(&#039;/~user/application-root/&#039;);
</pre>

    </div>

    <div class="section" id="zend.controller.router.global.parameters"><div class="info"><h1 class="title">Global Parameters</h1></div>
        

        <p class="para">
            You can set global parameters in a router which are automatically
            supplied to a route when assembling through
             <span class="methodname">setGlobalParam()</span>. If a global parameter is set
            but also given to the assemble method directly, the user parameter
            overrides the global parameter. You can set a global parameter this
            way:
        </p>

        <pre class="programlisting brush: php">
$router-&gt;setGlobalParam(&#039;lang&#039;, &#039;en&#039;);
</pre>

    </div>

    <div class="section" id="zend.controller.router.routes"><div class="info"><h1 class="title">Route Types</h1></div>
        
        <div class="section" id="zend.controller.router.routes.standard"><div class="info"><h1 class="title">Zend_Controller_Router_Route</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Controller_Router_Route</span> is the standard framework
        route. It combines ease of use with flexible route definition. Each
        route consists primarily of <acronym class="acronym">URL</acronym> mapping (of static and dynamic parts
        (variables)) and may be initialized with defaults as well as with
        variable requirements.
    </p>

    <p class="para">
        Let&#039;s imagine our fictional application will need some informational
        page about the content authors. We want to be able to point our web
        browsers to <var class="filename">http://domain.com/author/martel</var> to see the
        information about this &quot;martel&quot; guy. And the route for such
        functionality could look like:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route(
    &#039;author/:username&#039;,
    array(
        &#039;controller&#039; =&gt; &#039;profile&#039;,
        &#039;action&#039;     =&gt; &#039;userinfo&#039;
    )
);

$router-&gt;addRoute(&#039;user&#039;, $route);
</pre>


    <p class="para">
        The first parameter in the <span class="classname">Zend_Controller_Router_Route</span>
        constructor is a route definition that will be matched to a <acronym class="acronym">URL</acronym>. Route
        definitions consist of static and dynamic parts separated by the slash
        (&#039;/&#039;) character. Static parts are just simple text:
        <strong class="command">author</strong>. Dynamic parts, called variables, are marked by
        prepending a colon to the variable name: <strong class="command">:username</strong>.
    </p>

    <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Character Usage</b><br /></span>
        

        <p class="para">
            The current implementation allows you to use any character (except a
            slash) as a variable identifier, but it is strongly recommended that
            one uses only characters that are valid for <acronym class="acronym">PHP</acronym> variable
            identifiers. Future implementations may alter this behaviour, which
            could result in hidden bugs in your code.
        </p>
    </p></blockquote>

    <p class="para">
        This example route should be matched when you point your browser to
        <var class="filename">http://domain.com/author/martel</var>, in which case all its
        variables will be injected to the <span class="classname">Zend_Controller_Request</span>
        object and will be accessible in your <span class="classname">ProfileController</span>.
        Variables returned by this example may be represented as an array of
        the following key and value pairs:
    </p>

    <pre class="programlisting brush: php">
$values = array(
    &#039;username&#039;   =&gt; &#039;martel&#039;,
    &#039;controller&#039; =&gt; &#039;profile&#039;,
    &#039;action&#039;     =&gt; &#039;userinfo&#039;
);
</pre>


    <p class="para">
        Later on, <span class="classname">Zend_Controller_Dispatcher_Standard</span> should invoke
        the  <span class="methodname">userinfoAction()</span> method of your
        <span class="classname">ProfileController</span> class (in the default module) based on
        these values. There you will be able to access all variables by means of
        the  <span class="methodname">Zend_Controller_Action::_getParam()</span> or
         <span class="methodname">Zend_Controller_Request::getParam()</span> methods:
    </p>

    <pre class="programlisting brush: php">
public function userinfoAction()
{
    $request = $this-&gt;getRequest();
    $username = $request-&gt;getParam(&#039;username&#039;);

    $username = $this-&gt;_getParam(&#039;username&#039;);
}
</pre>


    <p class="para">
        Route definition can contain one more special character - a wildcard
        - represented by &#039;*&#039; symbol. It is used to gather parameters similarly
        to the default Module route (var =&gt; value pairs defined in the <acronym class="acronym">URI</acronym>). The
        following route more-or-less mimics the Module route behavior:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route(
    &#039;:module/:controller/:action/*&#039;,
    array(&#039;module&#039; =&gt; &#039;default&#039;)
);
$router-&gt;addRoute(&#039;default&#039;, $route);
</pre>


    <div class="section" id="zend.controller.router.routes.standard.variable-defaults"><div class="info"><h1 class="title">Variable Defaults</h1></div>
        

        <p class="para">
            Every variable in the route can have a default and this is what the
            second parameter of the <span class="classname">Zend_Controller_Router_Route</span>
            constructor is used for. This parameter is an array with keys
            representing variable names and with values as desired defaults:
        </p>

        <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route(
    &#039;archive/:year&#039;,
    array(&#039;year&#039; =&gt; 2006)
);
$router-&gt;addRoute(&#039;archive&#039;, $route);
</pre>


        <p class="para">
            The above route will match <acronym class="acronym">URL</acronym>s like
            <var class="filename">http://domain.com/archive/2005</var> and
            <var class="filename">http://example.com/archive</var>. In the latter case the
            variable year will have an initial default value of 2006.
        </p>

        <p class="para">
            This example will result in injecting a year variable to the request
            object. Since no routing information is present (no controller and
            action parameters are defined), the application will be dispatched
            to the default controller and action method (which are both defined
            in <span class="classname">Zend_Controller_Dispatcher_Abstract</span>). To make it
            more usable, you have to provide a valid controller and a valid
            action as the route&#039;s defaults:
        </p>

        <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route(
    &#039;archive/:year&#039;,
    array(
        &#039;year&#039;       =&gt; 2006,
        &#039;controller&#039; =&gt; &#039;archive&#039;,
        &#039;action&#039;     =&gt; &#039;show&#039;
    )
);
$router-&gt;addRoute(&#039;archive&#039;, $route);
</pre>


        <p class="para">
            This route will then result in dispatching to the method
             <span class="methodname">showAction()</span> of the class
            <span class="classname">ArchiveController</span>.
        </p>
    </div>

    <div class="section" id="zend.controller.router.routes.standard.variable-requirements"><div class="info"><h1 class="title">Variable Requirements</h1></div>
        

        <p class="para">
            One can add a third parameter to the
            <span class="classname">Zend_Controller_Router_Route</span> constructor where variable
            requirements may be set. These are defined as parts of a regular
            expression:
        </p>

        <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route(
    &#039;archive/:year&#039;,
    array(
        &#039;year&#039;       =&gt; 2006,
        &#039;controller&#039; =&gt; &#039;archive&#039;,
        &#039;action&#039;     =&gt; &#039;show&#039;
    ),
    array(&#039;year&#039; =&gt; &#039;\d+&#039;)
);
$router-&gt;addRoute(&#039;archive&#039;, $route);
</pre>


        <p class="para">
            With a route defined like above, the router will match it only when
            the year variable will contain numeric data, eg.
            <var class="filename">http://domain.com/archive/2345</var>. A <acronym class="acronym">URL</acronym> like
            <var class="filename">http://example.com/archive/test</var> will not be matched and
            control will be passed to the next route in the chain instead.
        </p>
    </div>

    <div class="section" id="zend.controller.router.routes.standard.translated-segments"><div class="info"><h1 class="title">Translated segments</h1></div>
        

        <p class="para">
            The standard route supports translated segments. To use this
            feature, you have to define at least a translator (an instance
            of <span class="classname">Zend_Translate</span>) via one of the following ways:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    Put it into the registry with the key <span class="classname">Zend_Translate</span>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Set it via the static method
                     <span class="methodname">Zend_Controller_Router_Route::setDefaultTranslator()</span>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Pass it as fourth parameter to the constructor.
                </p>
            </li>
        </ul>

        <p class="para">
            By default, the locale specified in the <span class="classname">Zend_Translate</span>
            instance will be used. To override it, you set it
            (an instance of <span class="classname">Zend_Locale</span> or a locale string) in one
            of the following ways:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    Put it into the registry with the key <span class="classname">Zend_Locale</span>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Set it via the static method
                     <span class="methodname">Zend_Controller_Router_Route::setDefaultLocale()</span>.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Pass it as fifth parameter to the constructor.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Pass it as <strong class="command">@locale</strong> parameter to the assemble
                    method.
                </p>
            </li>
        </ul>

        <p class="para">
            Translated segments are separated into two parts. Fixed segments
            are prefixed by a single <em class="emphasis">@</em>-sign, and will be
            translated to the current locale when assembling and reverted
            to the message ID when matching again. Dynamic segments
            are prefixed by <strong class="command">:@</strong>. When assembling, the given
            parameter will be translated and inserted into the parameter
            position. When matching, the translated parameter from the
            <acronym class="acronym">URL</acronym> will be reverted to the message ID again.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Message IDs and separate language file</b><br /></span>
            

            <p class="para">
                Occasionally a message ID which you want to use in one
                of your routes is already used in a view script or somewhere
                else. To have full control over safe <acronym class="acronym">URL</acronym>s, you should use
                a separate language file for the messages used in the route.
            </p>
        </p></blockquote>

        <p class="para">
            The following is the simplest way to prepare the standard route for
            translated segment usage:
        </p>

        <pre class="programlisting brush: php">
// Prepare the translator
$translator = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;array&#039;,
        &#039;content&#039; =&gt; array(),
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);
$translator-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt;
            array(
                &#039;archive&#039; =&gt; &#039;archiv&#039;,
                &#039;year&#039;    =&gt; &#039;jahr&#039;,
                &#039;month&#039;   =&gt; &#039;monat&#039;,
                &#039;index&#039;   =&gt; &#039;uebersicht&#039;
            ),
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);

// Set the current locale for the translator
$translator-&gt;setLocale(&#039;en&#039;);

// Set it as default translator for routes
Zend_Controller_Router_Route::setDefaultTranslator($translator);
</pre>


        <p class="para">
            This example demonstrates the usage of static segments:
        </p>

        <pre class="programlisting brush: php">
// Create the route
$route = new Zend_Controller_Router_Route(
    &#039;@archive&#039;,
    array(
        &#039;controller&#039; =&gt; &#039;archive&#039;,
        &#039;action&#039;     =&gt; &#039;index&#039;
    )
);
$router-&gt;addRoute(&#039;archive&#039;, $route);

// Assemble the URL in default locale: archive
$route-&gt;assemble(array());

// Assemble the URL in german: archiv
$route-&gt;assemble(array());
</pre>


        <p class="para">
            You can use the dynamic segments to create a module-route like
            translated version:
        </p>

        <pre class="programlisting brush: php">
// Create the route
$route = new Zend_Controller_Router_Route(
    &#039;:@controller/:@action/*&#039;,
    array(
        &#039;controller&#039; =&gt; &#039;index&#039;,
        &#039;action&#039;     =&gt; &#039;index&#039;
    )
);
$router-&gt;addRoute(&#039;archive&#039;, $route);

// Assemble the URL in default locale: archive/index/foo/bar
$route-&gt;assemble(array(&#039;controller&#039; =&gt; &#039;archive&#039;, &#039;foo&#039; =&gt; &#039;bar&#039;));

// Assemble the URL in german: archiv/uebersicht/foo/bar
$route-&gt;assemble(array(&#039;controller&#039; =&gt; &#039;archive&#039;, &#039;foo&#039; =&gt; &#039;bar&#039;));
</pre>


        <p class="para">
            You can also mix static and dynamic segments:
        </p>

        <pre class="programlisting brush: php">
// Create the route
$route = new Zend_Controller_Router_Route(
    &#039;@archive/:@mode/:value&#039;,
    array(
        &#039;mode&#039;       =&gt; &#039;year&#039;
        &#039;value&#039;      =&gt; 2005,
        &#039;controller&#039; =&gt; &#039;archive&#039;,
        &#039;action&#039;     =&gt; &#039;show&#039;
    ),
    array(&#039;mode&#039;  =&gt; &#039;(month|year)&#039;
          &#039;value&#039; =&gt; &#039;\d+&#039;)
);
$router-&gt;addRoute(&#039;archive&#039;, $route);

// Assemble the URL in default locale: archive/month/5
$route-&gt;assemble(array(&#039;mode&#039; =&gt; &#039;month&#039;, &#039;value&#039; =&gt; &#039;5&#039;));

// Assemble the URL in german: archiv/monat/5
$route-&gt;assemble(array(&#039;mode&#039; =&gt; &#039;month&#039;, &#039;value&#039; =&gt; &#039;5&#039;, &#039;@locale&#039; =&gt; &#039;de&#039;));
</pre>

    </div>
</div>
        <div class="section" id="zend.controller.router.routes.static"><div class="info"><h1 class="title">Zend_Controller_Router_Route_Static</h1></div>
    

    <p class="para">
        The examples above all use dynamic routes -- routes that contain
        patterns to match against. Sometimes, however, a particular route is
        set in stone, and firing up the regular expression engine would be
        an overkill. The answer to this situation is to use static routes:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Static(
    &#039;login&#039;,
    array(&#039;controller&#039; =&gt; &#039;auth&#039;, &#039;action&#039; =&gt; &#039;login&#039;)
);
$router-&gt;addRoute(&#039;login&#039;, $route);
</pre>


    <p class="para">
        Above route will match a <acronym class="acronym">URL</acronym> of
        <var class="filename">http://domain.com/login</var>, and dispatch to
         <span class="methodname">AuthController::loginAction()</span>.
    </p>

    <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Warning: Static Routes must Contain Sane Defaults</b><br /></span>
        

        <p class="para">
            Since a static route does not pass any part of the <acronym class="acronym">URL</acronym> to the
            request object as parameters, you <em class="emphasis">must</em> pass
            all parameters necessary for dispatching a request as defaults to
            the route. Omitting the &quot;controller&quot; or &quot;action&quot; default values will
            have unexpected results, and will likely result in the request being
            undispatchable.
        </p>

        <p class="para">
            As a rule of thumb, always provide each of the following default
            values:
        </p>

        <ul class="itemizedlist">
            <li class="listitem"><p class="para">controller</p></li>
            <li class="listitem"><p class="para">action</p></li>
            <li class="listitem"><p class="para">module (if not default)</p></li>
        </ul>

        <p class="para">
            Optionally, you can also pass the &quot;useDefaultControllerAlways&quot;
            parameter to the front controller during bootstrapping:
        </p>

        <pre class="programlisting brush: php">
$front-&gt;setParam(&#039;useDefaultControllerAlways&#039;, true);
</pre>


        <p class="para">
            However, this is considered a workaround; it is always better to
            explicitly define sane defaults.
        </p>
    </p></blockquote>
</div>
        <div class="section" id="zend.controller.router.routes.regex"><div class="info"><h1 class="title">Zend_Controller_Router_Route_Regex</h1></div>
    

    <p class="para">
        In addition to the default and static route types, a Regular
        Expression route type is available. This route offers more power and
        flexibility over the others, but at a slight cost of complexity. At the
        same time, it should be faster than the standard Route.
    </p>

    <p class="para">
        Like the standard route, this route has to be initialized with a route
        definition and some defaults. Let&#039;s create an archive route as an
        example, similar to the previously defined one, only using the Regex
        route this time:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Regex(
    &#039;archive/(\d+)&#039;,
    array(
        &#039;controller&#039; =&gt; &#039;archive&#039;,
        &#039;action&#039;     =&gt; &#039;show&#039;
    )
);
$router-&gt;addRoute(&#039;archive&#039;, $route);
</pre>


    <p class="para">
        Every defined regex subpattern will be injected to the request
        object. With our above example, after successful matching
        <var class="filename">http://domain.com/archive/2006</var>, the resulting value
        array may look like:
    </p>

    <pre class="programlisting brush: php">
$values = array(
    1            =&gt; &#039;2006&#039;,
    &#039;controller&#039; =&gt; &#039;archive&#039;,
    &#039;action&#039;     =&gt; &#039;show&#039;
);
</pre>


    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">
            Leading and trailing slashes are trimmed from the <acronym class="acronym">URL</acronym> in the Router
            prior to a match. As a result, matching the <acronym class="acronym">URL</acronym>
            <var class="filename">http://domain.com/foo/bar/</var>, would involve a regex of
            <var class="filename">foo/bar</var>, and not <var class="filename">/foo/bar</var>.
        </p>
    </p></blockquote>

    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">
            Line start and line end anchors (&#039;^&#039; and &#039;$&#039;, respectively) are
            automatically pre- and appended to all expressions. Thus, you
            should not use these in your regular expressions, and you should
            match the entire string.
        </p>
    </p></blockquote>

    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">
            This route class uses the &#039;<em class="emphasis">#</em>&#039; character for a delimiter.
            This means that you will need to escape hash characters (&#039;#&#039;) but
            not forward slashes (&#039;/&#039;) in your route definitions. Since the &#039;#&#039;
            character (named anchor) is rarely passed to the webserver, you will
            rarely need to use that character in your regex.
        </p>
    </p></blockquote>

    <p class="para">
        You can get the contents of the defined subpatterns the usual way:
    </p>

    <pre class="programlisting brush: php">
public function showAction()
{
    $request = $this-&gt;getRequest();
    $year    = $request-&gt;getParam(1); // $year = &#039;2006&#039;;
}
</pre>


    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">Notice the key is an integer (1) instead of a string (&#039;1&#039;).</p>
    </p></blockquote>

    <p class="para">
        This route will not yet work exactly the same as its standard route
        counterpart since the default for &#039;year&#039; is not yet set. And what may
        not yet be evident is that we will have a problem with a trailing slash
        even if we declare a default for the year and make the subpattern
        optional. The solution is to make the whole year part optional along
        with the slash but catch only the numeric part:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Regex(
    &#039;archive(?:/(\d+))?&#039;,
    array(
        1            =&gt; &#039;2006&#039;,
        &#039;controller&#039; =&gt; &#039;archive&#039;,
        &#039;action&#039;     =&gt; &#039;show&#039;
    )
);
$router-&gt;addRoute(&#039;archive&#039;, $route);
</pre>


    <p class="para">
        Now let&#039;s get to the problem you have probably noticed on your own by
        now. Using integer based keys for parameters is not an easily manageable
        solution and may be potentially problematic in the long run. And that&#039;s
        where the third parameter comes in. This parameter is an associative
        array that represents a map of regex subpatterns to parameter named
        keys. Let&#039;s work on our easier example:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Regex(
    &#039;archive/(\d+)&#039;,
    array(
        &#039;controller&#039; =&gt; &#039;archive&#039;,
        &#039;action&#039; =&gt; &#039;show&#039;
    ),
    array(
        1 =&gt; &#039;year&#039;
    )
);
$router-&gt;addRoute(&#039;archive&#039;, $route);
</pre>


    <p class="para">
        This will result in following values injected into Request:
    </p>

    <pre class="programlisting brush: php">
$values = array(
    &#039;year&#039;       =&gt; &#039;2006&#039;,
    &#039;controller&#039; =&gt; &#039;archive&#039;,
    &#039;action&#039;     =&gt; &#039;show&#039;
);
</pre>


    <p class="para">
        The map may be defined in either direction to make it work in any
        environment. Keys may contain variable names or subpattern indexes:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Regex(
    &#039;archive/(\d+)&#039;,
    array( ... ),
    array(1 =&gt; &#039;year&#039;)
);

// OR

$route = new Zend_Controller_Router_Route_Regex(
    &#039;archive/(\d+)&#039;,
    array( ... ),
    array(&#039;year&#039; =&gt; 1)
);
</pre>


    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">
            Subpattern keys have to be represented by integers.
        </p>
    </p></blockquote>

    <p class="para">
        Notice that the numeric index in Request values is now gone and a named
        variable is shown in its place. Of course you can mix numeric and named
        variables if you wish:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Regex(
    &#039;archive/(\d+)/page/(\d+)&#039;,
    array( ... ),
    array(&#039;year&#039; =&gt; 1)
);
</pre>


    <p class="para">
        Which will result in mixed values available in the Request. As an example, the
        <acronym class="acronym">URL</acronym> <var class="filename">http://domain.com/archive/2006/page/10</var>
        will result in following values:
    </p>

    <pre class="programlisting brush: php">
$values = array(
    &#039;year&#039;       =&gt; &#039;2006&#039;,
    2            =&gt; 10,
    &#039;controller&#039; =&gt; &#039;archive&#039;,
    &#039;action&#039;     =&gt; &#039;show&#039;
);
</pre>


    <p class="para">
        Since regex patterns are not easily reversed, you will need to prepare
        a reverse <acronym class="acronym">URL</acronym> if you wish to use a <acronym class="acronym">URL</acronym> helper or even
        an assemble method of this class. This reversed path is represented by a string parsable by
         <span class="methodname">sprintf()</span> and is defined as a fourth construct parameter:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Regex(
    &#039;archive/(\d+)&#039;,
    array( ... ),
    array(&#039;year&#039; =&gt; 1),
    &#039;archive/%s&#039;
);
</pre>


    <p class="para">
        All of this is something which was already possible by the means of a
        standard route object, so where&#039;s the benefit in using the Regex route,
        you ask? Primarily, it allows you to describe any type of <acronym class="acronym">URL</acronym> without
        any restrictions. Imagine you have a blog and wish to create <acronym class="acronym">URL</acronym>s like:
        <var class="filename">http://domain.com/blog/archive/01-Using_the_Regex_Router.html</var>,
        and have it decompose the last path element,
        <var class="filename">01-Using_the_Regex_Router.html</var>, into an article ID and
        article title or description; this is not possible with the standard route.
        With the Regex route, you can do something like the following solution:
    </p>

    <pre class="programlisting brush: php">
$route = new Zend_Controller_Router_Route_Regex(
    &#039;blog/archive/(\d+)-(.+)\.html&#039;,
    array(
        &#039;controller&#039; =&gt; &#039;blog&#039;,
        &#039;action&#039;     =&gt; &#039;view&#039;
    ),
    array(
        1 =&gt; &#039;id&#039;,
        2 =&gt; &#039;description&#039;
    ),
    &#039;blog/archive/%d-%s.html&#039;
);
$router-&gt;addRoute(&#039;blogArchive&#039;, $route);
</pre>


    <p class="para">
        As you can see, this adds a tremendous amount of flexibility over the
        standard route.
    </p>
</div>
        <div class="section" id="zend.controller.router.routes.hostname"><div class="info"><h1 class="title">Zend_Controller_Router_Route_Hostname</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Controller_Router_Route_Hostname</span> is the hostname route of
        the framework. It works similar to the standard route, but it works on
        the with the hostname of the called <acronym class="acronym">URL</acronym> instead with the path.
    </p>

    <p class="para">
        Let&#039;s use the example from the standard route and see how it would look
        like in a hostname based way. Instead of calling the user via a path,
        we&#039;d want to have a user to be able to call
        <var class="filename">http://martel.users.example.com</var> to see the information
        about the user &quot;martel&quot;:
    </p>

    <pre class="programlisting brush: php">
$hostnameRoute = new Zend_Controller_Router_Route_Hostname(
    &#039;:username.users.example.com&#039;,
    array(
        &#039;controller&#039; =&gt; &#039;profile&#039;,
        &#039;action&#039;     =&gt; &#039;userinfo&#039;
    )
);

$plainPathRoute = new Zend_Controller_Router_Route_Static(&#039;&#039;);

$router-&gt;addRoute(&#039;user&#039;, $hostnameRoute-&gt;chain($plainPathRoute));
</pre>


    <p class="para">
        The first parameter in the <span class="classname">Zend_Controller_Router_Route_Hostname</span>
        constructor is a route definition that will be matched to a hostname. Route
        definitions consist of static and dynamic parts separated by the dot
        (&#039;.&#039;) character. Dynamic parts, called variables, are marked by
        prepending a colon to the variable name: <strong class="command">:username</strong>.
        Static parts are just simple text: <strong class="command">user</strong>.
    </p>

    <p class="para">
        Hostname routes can, but never should be used as is. The reason behind
        that is, that a hostname route alone would match any path. So what you
        have to do is to chain a path route to the hostname route. This is done
        like in the example by calling <strong class="command">$hostnameRoute-&gt;chain($pathRoute);</strong>.
        By doing this, <var class="varname">$hostnameRoute</var> isn&#039;t modified, but a new
        route (<span class="classname">Zend_Controller_Router_Route_Chain</span>) is returned,
        which can then be given to the router.
    </p>
</div>
        <div class="section" id="zend.controller.router.routes.chain"><div class="info"><h1 class="title">Zend_Controller_Router_Route_Chain</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Controller_Router_Route_Chain</span> is a route which allows
        to chain multiple routes together. This allows you to chain
        hostname-routes and path routes, or multiple path routes for example.
        Chaining can be done either programatically or within a configuration
        file.
    </p>

    <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Parameter Priority</b><br /></span>
        

        <p class="para">
            When chaining routes together, the parameters of the outer route
            have a higher priority than the parameters of the inner route. Thus
            if you define a controller in the outer and in the inner route,
            the controller of the outer route will be selected.
        </p>
    </p></blockquote>

    <p class="para">
        When chaining programatically, there are two ways to achieve this. The
        first one is to create a new
        <span class="classname">Zend_Controller_Router_Route_Chain</span> instance and then
        calling the  <span class="methodname">chain()</span> method multiple times with all routes
        which should be chained together. The other way is to take the first
        route, e.g. a hostname route, and calling the  <span class="methodname">chain()</span>
        method on it with the route which should be appended to it. This
        will not modify the hostname route, but return a new instance of
        <span class="classname">Zend_Controller_Router_Route_Chain</span>, which then has both
        routes chained together:
    </p>

    <pre class="programlisting brush: php">
// Create two routes
$hostnameRoute = new Zend_Controller_Router_Route_Hostname(...);
$pathRoute     = new Zend_Controller_Router_Route(...);

// First way, chain them via the chain route
$chainedRoute = new Zend_Controller_Router_Route_Chain();
$chainedRoute-&gt;chain($hostnameRoute)
             -&gt;chain($pathRoute);

// Second way, chain them directly
$chainedRoute = $hostnameRoute-&gt;chain($pathRoute);
</pre>


    <p class="para">
        When chaining routes together, their separator is a slash
        by default. There may be cases when you want to have a different
        separator:
    </p>

    <pre class="programlisting brush: php">
// Create two routes
$firstRoute  = new Zend_Controller_Router_Route(&#039;foo&#039;);
$secondRoute = new Zend_Controller_Router_Route(&#039;bar&#039;);

// Chain them together with a different separator
$chainedRoute = $firstRoute-&gt;chain($secondRoute, &#039;-&#039;);

// Assemble the route: &quot;foo-bar&quot;
echo $chainedRoute-&gt;assemble();
</pre>


    <div class="section" id="zend.controller.router.routes.chain.config"><div class="info"><h1 class="title">Chain Routes via Zend_Config</h1></div>
        

        <p class="para">
            To chain routes together in a config file, there are additional
            parameters for the configuration of those. The simpler approach is
            to use the <span class="property">chains</span> parameters. This one is simply a list
            of routes, which will be chained with the parent route. Neither the
            parent- nor the child-route will be added directly to the router but
            only the resulting chained route. The name of the chained route in
            the router will be the parent route name and the child route name
            concatenated with a dash (-) by default. A simple config in <acronym class="acronym">XML</acronym>
            would look like this:
        </p>

        <pre class="programlisting brush: xml">
&lt;routes&gt;
    &lt;www type=&quot;Zend_Controller_Router_Route_Hostname&quot;&gt;
        &lt;route&gt;www.example.com&lt;/route&gt;
        &lt;chains&gt;
            &lt;language type=&quot;Zend_Controller_Router_Route&quot;&gt;
                &lt;route&gt;:language&lt;/route&gt;
                &lt;reqs language=&quot;[a-z]{2}&quot;&gt;
                &lt;chains&gt;
                    &lt;index type=&quot;Zend_Controller_Router_Route_Static&quot;&gt;
                        &lt;route&gt;&lt;/route&gt;
                        &lt;defaults module=&quot;default&quot; controller=&quot;index&quot;
                                  action=&quot;index&quot; /&gt;
                    &lt;/index&gt;
                    &lt;imprint type=&quot;Zend_Controller_Router_Route_Static&quot;&gt;
                        &lt;route&gt;imprint&lt;/route&gt;
                        &lt;defaults module=&quot;default&quot; controller=&quot;index&quot;
                                  action=&quot;index&quot; /&gt;
                    &lt;/imprint&gt;
                &lt;/chains&gt;
            &lt;/language&gt;
        &lt;/chains&gt;
    &lt;/www&gt;
    &lt;users type=&quot;Zend_Controller_Router_Route_Hostname&quot;&gt;
        &lt;route&gt;users.example.com&lt;/route&gt;
        &lt;chains&gt;
            &lt;profile type=&quot;Zend_Controller_Router_Route&quot;&gt;
                &lt;route&gt;:username&lt;/route&gt;
                &lt;defaults module=&quot;users&quot; controller=&quot;profile&quot; action=&quot;index&quot; /&gt;
            &lt;/profile&gt;
        &lt;/chains&gt;
    &lt;/users&gt;
    &lt;misc type=&quot;Zend_Controller_Router_Route_Static&quot;&gt;
        &lt;route&gt;misc&lt;/route&gt;
    &lt;/misc&gt;
&lt;/routes&gt;
</pre>


        <p class="para">
            This will result in the three routes <strong class="command">www-language-index</strong>,
            <strong class="command">www-language-imprint</strong> and
            <strong class="command">users-language-profile</strong> which will only match based on
            the hostname and the route <strong class="command">misc</strong>, which will match with
            any hostname.
        </p>

        <p class="para">
            The alternative way of creating a chained route is via the
            <span class="property">chain</span> parameter, which can only be used with the
            chain-route type directly, and also just works in the root level:
        </p>

        <pre class="programlisting brush: xml">
&lt;routes&gt;
    &lt;www type=&quot;Zend_Controller_Router_Route_Chain&quot;&gt;
        &lt;route&gt;www.example.com&lt;/route&gt;
    &lt;/www&gt;
    &lt;language type=&quot;Zend_Controller_Router_Route&quot;&gt;
        &lt;route&gt;:language&lt;/route&gt;
        &lt;reqs language=&quot;[a-z]{2}&quot;&gt;
    &lt;/language&gt;
    &lt;index type=&quot;Zend_Controller_Router_Route_Static&quot;&gt;
        &lt;route&gt;&lt;/route&gt;
        &lt;defaults module=&quot;default&quot; controller=&quot;index&quot; action=&quot;index&quot; /&gt;
    &lt;/index&gt;
    &lt;imprint type=&quot;Zend_Controller_Router_Route_Static&quot;&gt;
        &lt;route&gt;imprint&lt;/route&gt;
        &lt;defaults module=&quot;default&quot; controller=&quot;index&quot; action=&quot;index&quot; /&gt;
    &lt;/imprint&gt;

    &lt;www-index type=&quot;Zend_Controller_Router_Route_Chain&quot;&gt;
        &lt;chain&gt;www, language, index&lt;/chain&gt;
    &lt;/www-index&gt;
    &lt;www-imprint type=&quot;Zend_Controller_Router_Route_Chain&quot;&gt;
        &lt;chain&gt;www, language, imprint&lt;/chain&gt;
    &lt;/www-imprint&gt;
&lt;/routes&gt;
</pre>


        <p class="para">
            You can also give the <span class="property">chain</span> parameter as array instead
            of separating the routes with a comma:
        </p>

        <pre class="programlisting brush: xml">
&lt;routes&gt;
    &lt;www-index type=&quot;Zend_Controller_Router_Route_Chain&quot;&gt;
        &lt;chain&gt;www&lt;/chain&gt;
        &lt;chain&gt;language&lt;/chain&gt;
        &lt;chain&gt;index&lt;/chain&gt;
    &lt;/www-index&gt;
    &lt;www-imprint type=&quot;Zend_Controller_Router_Route_Chain&quot;&gt;
        &lt;chain&gt;www&lt;/chain&gt;
        &lt;chain&gt;language&lt;/chain&gt;
        &lt;chain&gt;imprint&lt;/chain&gt;
    &lt;/www-imprint&gt;
&lt;/routes&gt;
</pre>


        <p class="para">
            When you configure chain routes with <span class="classname">Zend_Config</span> and
            want the chain name separator to be different from a dash, you
            need to specify this separator separately:
        </p>

        <pre class="programlisting brush: php">
$config = new Zend_Config(array(
    &#039;chainName&#039; =&gt; array(
        &#039;type&#039;   =&gt; &#039;Zend_Controller_Router_Route_Static&#039;,
        &#039;route&#039;  =&gt; &#039;foo&#039;,
        &#039;chains&#039; =&gt; array(
            &#039;subRouteName&#039; =&gt; array(
                &#039;type&#039;     =&gt; &#039;Zend_Controller_Router_Route_Static&#039;,
                &#039;route&#039;    =&gt; &#039;bar&#039;,
                &#039;defaults&#039; =&gt; array(
                    &#039;module&#039;      =&gt; &#039;module&#039;,
                     &#039;controller&#039; =&gt; &#039;controller&#039;,
                     &#039;action&#039;     =&gt; &#039;action&#039;
                )
            )
        )
    )
));

// Set separator before adding config
$router-&gt;setChainNameSeparator(&#039;_separator_&#039;)

// Add config
$router-&gt;addConfig($config);

// The name of our route now is: chainName_separator_subRouteName
echo $this-&gt;_router-&gt;assemble(array(), &#039;chainName_separator_subRouteName&#039;);

// The proof: it echoes /foo/bar
</pre>

    </div>
</div>
        <div class="section" id="zend.controller.router.routes.rest"><div class="info"><h1 class="title">Zend_Rest_Route</h1></div>
    

    <p class="para">
        The <span class="classname">Zend_Rest</span> component contains a RESTful route
        for <span class="classname">Zend_Controller_Router_Rewrite</span>. This route
        offers a standardized routing scheme that routes requests by translating
        the <acronym class="acronym">HTTP</acronym> method and the <acronym class="acronym">URI</acronym>
        to a module, controller, and action. The table below provides an overview
        of how request methods and <acronym class="acronym">URI</acronym>&#039;s are routed.
    </p>

    <table class="doctable table"><div class="info"><caption><b>Zend_Rest_Route Behavior</b></caption></div>
        

        
            <col align="left" />
            <col align="left" />
            <col align="left" />

            <thead valign="middle">
                <tr valign="middle">
                    <th>Method</th>
                    <th><acronym class="acronym">URI</acronym></th>
                    <th>Module_Controller::action</th>
                </tr>

            </thead>


            <tbody valign="middle" class="tbody">
                <tr valign="middle">
                    <td align="left"><b><tt>GET</tt></b></td>
                    <td align="left"><var class="filename">/product/ratings/</var></td>
                    <td align="left"> <span class="methodname">Product_RatingsController::indexAction()</span></td>
                </tr>


                <tr valign="middle">
                    <td align="left"><b><tt>GET</tt></b></td>
                    <td align="left"><var class="filename">/product/ratings/:id</var></td>
                    <td align="left"> <span class="methodname">Product_RatingsController::getAction()</span></td>
                </tr>


                <tr valign="middle">
                    <td align="left"><b><tt>POST</tt></b></td>
                    <td align="left"><var class="filename">/product/ratings</var></td>
                    <td align="left"> <span class="methodname">Product_RatingsController::postAction()</span></td>
                </tr>


                <tr valign="middle">
                    <td align="left"><b><tt>PUT</tt></b></td>
                    <td align="left"><var class="filename">/product/ratings/:id</var></td>
                    <td align="left"> <span class="methodname">Product_RatingsController::putAction()</span></td>
                </tr>


                <tr valign="middle">
                    <td align="left"><b><tt>DELETE</tt></b></td>
                    <td align="left"><var class="filename">/product/ratings/:id</var></td>

                    <td align="left">
                         <span class="methodname">Product_RatingsController::deleteAction()</span>
                    </td>
                </tr>


                <tr valign="middle">
                    <td align="left"><b><tt>POST</tt></b></td>
                    <td align="left"><var class="filename">/product/ratings/:id?_method=PUT</var></td>
                    <td align="left"> <span class="methodname">Product_RatingsController::putAction()</span></td>
                </tr>


                <tr valign="middle">
                    <td align="left"><b><tt>POST</tt></b></td>
                    <td align="left"><var class="filename">/product/ratings/:id?_method=DELETE</var></td>

                    <td align="left">
                         <span class="methodname">Product_RatingsController::deleteAction()</span>
                    </td>
                </tr>

            </tbody>
        
    </table>


    <div class="section" id="zend.rest.route_usage"><div class="info"><h1 class="title">Zend_Rest_Route Usage</h1></div>
        

        <p class="para">
            To enable <span class="classname">Zend_Rest_Route</span> for an entire
            application, construct it with no config params and add it as the
            default route on the front controller:
        </p>

        <pre class="programlisting brush: php">
$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front);
$front-&gt;getRouter()-&gt;addRoute(&#039;default&#039;, $restRoute);
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                If <span class="classname">Zend_Rest_Route</span> cannot match a valid
                module, controller, or action, it will return <b><tt>FALSE</tt></b> and the
                router will attempt to match using the next route in the router.
            </p>
        </p></blockquote>

        <p class="para">
            To enable <span class="classname">Zend_Rest_Route</span> for specific modules,
            construct it with an array of module names as the 3rd constructor argument:
        </p>

        <pre class="programlisting brush: php">
$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front, array(), array(&#039;product&#039;));
$front-&gt;getRouter()-&gt;addRoute(&#039;rest&#039;, $restRoute);
</pre>


        <p class="para">
            To enable <span class="classname">Zend_Rest_Route</span> for specific
            controllers, add an array of controller names as the value of each module array element.
        </p>

        <pre class="programlisting brush: php">
$front     = Zend_Controller_Front::getInstance();
$restRoute = new Zend_Rest_Route($front, array(), array(
    &#039;product&#039; =&gt; array(&#039;ratings&#039;)
));
$front-&gt;getRouter()-&gt;addRoute(&#039;rest&#039;, $restRoute);
</pre>

    </div>

    <div class="section" id="zend.rest.route_config"><div class="info"><h1 class="title">Zend_Rest_Route with Zend_Config_Ini</h1></div>
        

        <p class="para">
            To use <span class="classname">Zend_Rest_Route</span> from an <acronym class="acronym">INI</acronym> config
            file, use a route type parameter and set the config options:
        </p>

        <pre class="programlisting brush: ini">
routes.rest.type = Zend_Rest_Route
routes.rest.defaults.controller = object
routes.rest.mod = project,user
</pre>


        <p class="para">
            The &#039;type&#039; option designates the RESTful routing config type. The &#039;defaults&#039; option is
            used to specify custom default module, controller, and/or actions for the route. All
            other options in the config group are treated as RESTful module names, and their values
            are RESTful controller names. The example config defines
            <span class="classname">Mod_ProjectController</span> and
            <span class="classname">Mod_UserController</span> as RESTful controllers.
        </p>

        <p class="para">
            Then use the  <span class="methodname">addConfig()</span> method of the Rewrite router object:
        </p>

        <pre class="programlisting brush: php">
$config = new Zend_Config_Ini(&#039;path/to/routes.ini&#039;);
$router = new Zend_Controller_Router_Rewrite();
$router-&gt;addConfig($config, &#039;routes&#039;);
</pre>

    </div>

    <div class="section" id="zend.rest.controller"><div class="info"><h1 class="title">Zend_Rest_Controller</h1></div>
        

        <p class="para">
            To help or guide development of Controllers for use with
            <span class="classname">Zend_Rest_Route</span>, extend your Controllers from
            <span class="classname">Zend_Rest_Controller</span>.
            <span class="classname">Zend_Rest_Controller</span> defines the 5 most-commonly
            needed operations for RESTful resources in the form of abstract action
            methods.
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis"> <span class="methodname">indexAction()</span></em> -
                    Should retrieve an index of resources and assign it to view.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis"> <span class="methodname">getAction()</span></em> -
                    Should retrieve a single resource identified by <acronym class="acronym">URI</acronym>
                    and assign it to view.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis"> <span class="methodname">postAction()</span></em> -
                    Should accept a new single resource and persist its state.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis"> <span class="methodname">putAction()</span></em> -
                    Should accept a single resource idenitifed by <acronym class="acronym">URI</acronym>
                    and persist its state.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis"> <span class="methodname">deleteAction()</span></em> -
                    Should delete a single resource identified by <acronym class="acronym">URI</acronym>.
                </p>
            </li>
        </ul>
    </div>
</div>
    </div>

    <div class="section" id="zend.controller.router.add-config"><div class="info"><h1 class="title">Using Zend_Config with the RewriteRouter</h1></div>
        

        <p class="para">
            Sometimes it is more convenient to update a configuration file with
            new routes than to change the code. This is possible via the
             <span class="methodname">addConfig()</span> method. Basically, you create a
            <span class="classname">Zend_Config</span>-compatible configuration, and in your code read it in
            and pass it to the RewriteRouter.
        </p>

        <p class="para">
            As an example, consider the following <acronym class="acronym">INI</acronym> file:
        </p>

        <pre class="programlisting brush: php">
[production]
routes.archive.route = &quot;archive/:year/*&quot;
routes.archive.defaults.controller = archive
routes.archive.defaults.action = show
routes.archive.defaults.year = 2000
routes.archive.reqs.year = &quot;\d+&quot;

routes.news.type = &quot;Zend_Controller_Router_Route_Static&quot;
routes.news.route = &quot;news&quot;
routes.news.defaults.controller = &quot;news&quot;
routes.news.defaults.action = &quot;list&quot;

routes.archive.type = &quot;Zend_Controller_Router_Route_Regex&quot;
routes.archive.route = &quot;archive/(\d+)&quot;
routes.archive.defaults.controller = &quot;archive&quot;
routes.archive.defaults.action = &quot;show&quot;
routes.archive.map.1 = &quot;year&quot;
; OR: routes.archive.map.year = 1
</pre>


        <p class="para">
            The above <acronym class="acronym">INI</acronym> file can then be read into a
            <span class="classname">Zend_Config</span> object as follows:
        </p>

        <pre class="programlisting brush: php">
$config = new Zend_Config_Ini(&#039;/path/to/config.ini&#039;, &#039;production&#039;);
$router = new Zend_Controller_Router_Rewrite();
$router-&gt;addConfig($config, &#039;routes&#039;);
</pre>


        <p class="para">
            In the above example, we tell the router to use the &#039;routes&#039; section
            of the <acronym class="acronym">INI</acronym> file to use for its routes. Each first-level key under
            that section will be used to define a route name; the above example
            defines the routes &#039;archive&#039; and &#039;news&#039;. Each route then requires,
            at minimum, a &#039;route&#039; entry and one or more &#039;defaults&#039; entries;
            optionally one or more &#039;reqs&#039; (short for &#039;required&#039;) may be
            provided. All told, these correspond to the three arguments provided
            to a <span class="classname">Zend_Controller_Router_Route_Interface</span> object. An
            option key, &#039;type&#039;, can be used to specify the route class type to
            use for that particular route; by default, it uses
            <span class="classname">Zend_Controller_Router_Route</span>. In the example above, the
            &#039;news&#039; route is defined to use
            <span class="classname">Zend_Controller_Router_Route_Static</span>.
        </p>
    </div>

    <div class="section" id="zend.controller.router.subclassing"><div class="info"><h1 class="title">Subclassing the Router</h1></div>
        

        <p class="para">
            The standard rewrite router should provide most functionality you
            may need; most often, you will only need to create a new route type
            in order to provide new or modified functionality over the provided
            routes.
        </p>

        <p class="para">
            That said, you may at some point find yourself wanting to use a
            different routing paradigm. The interface
            <span class="classname">Zend_Controller_Router_Interface</span> provides the minimal
            information required to create a router, and consists of a single
            method.
        </p>

        <pre class="programlisting brush: php">
interface Zend_Controller_Router_Interface
{
  /**
   * @param  Zend_Controller_Request_Abstract $request
   * @throws Zend_Controller_Router_Exception
   * @return Zend_Controller_Request_Abstract
   */
  public function route(Zend_Controller_Request_Abstract $request);
}
</pre>


        <p class="para">
            Routing only occurs once: when the request is first received into
            the system. The purpose of the router is to determine the
            controller, action, and optional parameters based on the request
            environment, and then set them in the request. The request object
            is then passed to the dispatcher. If it is not possible to map a
            route to a dispatch token, the router should do nothing to the
            request object.
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.controller.request.html">The Request Object</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.controller.html">Zend_Controller</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.controller.dispatcher.html">The Dispatcher</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.controller.html">Zend_Controller</a></li>
  <li><a href="zend.controller.quickstart.html">Zend_Controller Quick Start</a></li>
  <li><a href="zend.controller.basics.html">Zend_Controller Basics</a></li>
  <li><a href="zend.controller.front.html">The Front Controller</a></li>
  <li><a href="zend.controller.request.html">The Request Object</a></li>
  <li class="active"><a href="zend.controller.router.html">The Standard Router</a></li>
  <li><a href="zend.controller.dispatcher.html">The Dispatcher</a></li>
  <li><a href="zend.controller.action.html">Action Controllers</a></li>
  <li><a href="zend.controller.actionhelpers.html">Action Helpers</a></li>
  <li><a href="zend.controller.response.html">The Response Object</a></li>
  <li><a href="zend.controller.plugins.html">Plugins</a></li>
  <li><a href="zend.controller.modular.html">Using a Conventional Modular Directory Structure</a></li>
  <li><a href="zend.controller.exceptions.html">MVC Exceptions</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>